Aminet 15/Aminet 15 - Nov 1996.iso/Aminet/dev/misc/AutoGuideCreat.lha/AutoGuideCreator/Italian_PROGRAMMERS.READM

Text File | 1996-09-02 | 11.3 KB | 218 lines

    AUTOGUIDE CREATOR

    SISTEMA DI SVILUPPO IN ASSEMBLER


Dato che programmo sempre e solo in assembler (fin dal lontano C 64), ho
trovato utile avere sempre disponibile la descrizione dei comandi e loro
connessi delle librerie dell' amiga. Per fare questo era già presente un
programma in PD in grado di ottenere (peraltro in maniera molto
macchinosa) un file guide di riferimento e i relativi file guide per ogni
libreria o device, ecc... Quest' ultimo programma non è però in grado di
operare alcun controllo sulla sintassi, nè riusciva a creare dei file
guide veramente perfetti per ciò che riguardava i collegamenti con gli
altri file e/o con le descrizioni delle strutture; per non dimenticare la
impossibilità di generare un indice delle macro presenti nei file .i degli
include.Inoltre poteva solo controllare i file .h degli include (utili
solo per i programmatori in C). Il programma che ho sviluppato è in grado
di leggere sia gli include di tipo .h che quelli di tipo .i (quindi di
creare dei file guide per entrambi i tipi di programmatori), leggere gli
autodoc, controllarne l'esatta sintassi, stabilire un ordine alfabetico di
tutte le varie funzioni e strutture (sia nell' indice generale che in
quello particolare di ogni singolo file guide - indipendentemente dall'
ordine in cui essi sono stati scritti), ed infine creare sia i singoli
file guide da ogni autodoc, sia un  file indice generale (TOC) nel quale
sono anche riuniti un indice per funzioni, strutture e macro (quest'ultime
solo nel caso si scelga il linguaggio assembler).

    SVILUPPO INIZIALE DEL PROGRAMMA

Il primo programma da me creato non aveva un interfaccia intuition, ed
esso è costituito dalla parte 'AUTOGUIDE.INT' che viene inclusa nel
programma principale.

     All'inizio esso parte dalla elaborazione dei file presenti in una
    directory già prefissata nel programma
    Da essa vengono prelevati i file doc, che subiscono dapprima il
    controllo sintassi    (vedi la parte stx_ctr del programma)
    -  i  file  nei  quali  siano  presenti  gli  errori  vengono  memorizzati
    (e così anche il tipo di errore) per essere poi elencati nel file ERROR ed
    anche nella  finestra di controllo del programma.
           Vengono quindi controllate le funzioni descritte in quel
           determinato file doc e memorizzate secondo il nome ed il file
           di appartenenza (serviranno poi come indice delle funzioni per
           la costruzione del cross-link tra i varii file).

 In seguito vengono controllati i file include per la presenza delle
 strutture e delle macro e la loro posizione nei relativi file viene memorizzata, per essere poi inclusa
 nella descrizione dei file guide.
 Come per i file doc, si creerà quindi un indice delle strutture per i
 successivi cross-link.

Inoltre si creerà un indice dei tipi di file doc (device, library,
datatype ecc...), utile nella stesura ordinata del file TOC principale.

Tutti gli indici creati si basano su strutture da me appositamente create
per l' ordinamento degli stessi (questo facilita in seguito la
elaborazione dei file guide).

Fatto questo si procede alla elaborazione dei file doc (tranne nel caso in
cui vi siano errori, per cui il programma potrebbe andare in crash, a
causa del superamento in fase di ricerca delle varie funzioni e strutture)
Tale elaborazione tiene conto di varie strutture presenti nei file doc:

    -    caratteri FF (a capo)    indici di termine descrizione lista
    funzioni o della singola funzione o di tutto il file ( ciò serve
    anche come riferimento nella trascrizione del file guide a partire
    dal doc originale, per impegnare meno memoria nella elaborazione)

    -    PAROLE IN GRASSETTO        individua    le parole da scrivere in
    grassetto (non presente in altri programmi precedenti)

    -    STRUTTURE                individua le strutture da linkare nel
        file doc


    -    FILE INCLUDE            individua la presenza di un riferimento
    ad un file include (sua descrizione). Per ora questo riferimento
    viene solo individuato ma non si controlla se quel file è presente
    nella directory indicata, sarà uno sviluppo futuro.

    -    FUNZIONI                individua le funzioni da linkare
    associando sia quelle del file in esame sia quelle presenti negli
    altri file doc, escludendo la eventuale ripetizione della stessa
    funzione che si sta descrivendo (è inutile creare un tasto di
    associazione per la stessa funzione che si sta esminando !! - modo
    non presente in altri programmi precedenti )

In questo modo si crea un indice di riferimento per la costruzione del
file guide, che avviene in seguito, dopo avere ordinato in sequenza tutti
i riferimenti ottenuti dalla precedente ricerca. Ciò avviene per tutti i
file doc presenti nella directory prescelta, quindi si procede alla
costruzione del file TOC, indice generale di tutti i file guide ottenuti
ed anche indice analitico di tutte le funzioni, strutture (e macro nel
caso del linguaggio assembler - opzione quest'ultima presente solo in
questo programma !!).

Per fare tutto ciò ho utilizzato in maniera continuativa il comando
ParsePattern (perdendo un mucchio di tempo per trovare l' esatta
definizione delle parole chiave, soprattutto per le funzioni, la cui
parola chiave è sempre il riferimento "()" al termine della parola stessa
- vedasi la definizione della parola Sstruct ed Sfunct nel file
AUTOGUIDE.INT-)

Il programma aveva però il limite di definire sia la directory dei file
doc sia quella dei file include senza possibilità di scelta. Ho quindi
pensato alla interfaccia intuition, la cui costruzione è affidata al
programma AUTOGUIDE.S, che poi è il programma di partenza per
l'assemblaggio finale:

Per l'intuition ho fatto uso della libreria Gadtools e della funzione
CreateGadget (pertanto il programma non può funzionare al di sotto della
versione 37-38 del SO) Tutti i gadget vengono creati PRIMA di aprire la
finestra (anche quelli riguardanti la finestra OPZIONI) Tramite questi è
possibile la scelta (mediante la libreria ASL) delle varie directory: in
questo modo è possibile evitare l'uso delle assegnazioni ai path di
appartenenza dei file include    (impossibile ad altri programma analoghi
precedenti !), che viene automaticamente inclusa nei file guide elaborati.

Un altra caratteristica del programma (per le versioni di Amigaguide >38)
è la possibilità di utilizzare i vari tipi di scrittura (nello specifico
in grassetto - non presente in altri programmi analoghi), per la quale ho
pensato alla possibilità di scelta delle parole da trascrivere in un
determinato modo; a questo punto, ed anche per scegliere le funzioni da
evitare (perchè analoghe ad altre presenti in file guide diversi), ho
creato il tasto OPZIONI che apre un nuova finestra con 2 listview che
permettono la scelta ed il cambiamento in maniera rapida di tali
parametri. Questi parametri vengono poi descritti nel file ASCII
AUTOGUIDE.PREFS che può essere variato (vedi il file autoguide.doc) anche
prima della esecuzione del programma per variare tali parametri.


Infine il programma crea il file binario (NOME TOC).XREF che è un indice
delle funzioni e relativi file guide, delle parole in grassetto, delle
funzioni da evitare, del nome del file TOC e del tipo di linguaggio usato
e la directory di riferimento dei file include, che servirà per un
eventuale aggiornamento del file TOC con nuovi autodoc (o aggiornamento di
vecchi autodoc già presenti).

La funzione ADD AUTODOC è stata più complessa da definire: essa non solo
permette di aggiungere nuovi file a quelli già presenti (e li riordina
anche nel file TOC), ma anche di cambiare quelli già presenti (con
eventuali aggiornamenti); questo avviene sempre a scelta da parte
dell'utente grazie ad un requester che appare sempre per richiedere
conferma al cambiamento. Inoltre il cambiamento impone la esclusione delle
vecchie funzioni dal file .XREF e la sua ritrascrizione, questa è una
delle parti più complesse del programma, poichè comprende tali variazioni
in qualsiasi parte del file esse si trovino. Sicuramente l'avere ordinato
tutti gli indici usati mediante l'uso di STRUTTURE create ex-novo, mi ha
molto facilitato in tutto questo.

Al termine della funzione New Guide il programma richiede (ricercandola
nella dir > envarc/sys), un icona da assegnare al file TOC. Se questo non
avviene, non accade nulla, solo non si assegna nessun icona al file (però
questo determina la necessità di visualizzare tutti i file della directory
dei file guide !!) Tale funzione non avviene nel caso dell' ADD AUTODOC,
in quanto qui è sufficente cambiare il solo file TOC e non la sua icona.

Tra le varie funzioni del programma vi è la capacità di creare un cassetto
per la directory dei file guide (ed assegnarvi automaticamente un icona di
tale tipo), che può essere scelto dall' utente. Ed infine la capacità
(solo nelle versioni 3.0 ed oltre del SO), di iconificare la finestra
principale del programma (sulla quale però appare ancora la descrizione
della funzione svolta in quel momento), per intenderci alla maniera di
Directory Opus.

Una volta compilato (da devpac in modo eseguibile) il programma occupa
poco più di 30 Kbyte (in maniera blink supera i 65 Kb), però è ingrado di
manipolare file di qualsiasi lunghezza ed un numero infinito di autodoc da
elaborare (tutto è limitato dalla quantità di memoria disponibile, però
funziona egregiamente anche con solo 1 Mbyte).

Ho potuto elaborare in questo modo tutti i file autodoc presenti nel
devkit 3.1 (in circa 25 minuti con accelleratrice 68030 e 8 Mbyte sul mio
A 1200, contro le ore necessarie nella stessa configurazione da parte del
programma AD2HT !), ed in seguito aggiungerne altri 3 trovati per altre
librerie presenti nel PD.

Il Multitasking viene mantenuto lo stesso, ho avuto solo qualche problema
con Direcory Opus 4 (non con il 5.11 !!). Nel caso la directory per i file
guide venga creata ex-novo, essa non sarà disponibile fino al termine
della esecuzione del programma (questo invece non accade se viene usata un
dir già presente).

La parte più complessa della elaborazione è stata sicuramente la ricerca
della definizione delle parole chiave per la ricerca delle funzioni
(questo ha mandato in crash a volte l'intero programma, a causa dello
sconfinamento oltre la memoria disponibile della funzione ParsePattern,
che, devo ammettere, è estremamente potente ed affidabile. La maggior
parte del tempo perso dal programma è proprio quella riguardante tale
funzione, perciò essa stessa è stata riscritta più volte, fino a farla
divenire una subroutine utile per tutte le ricerche di tutte le paorle
chiave.

Il sistema delle subroutine è sicuramente meno leggibile dal
programmatore, ma è quella che assicura più risparmio di memoria e di
tempo di esecuzione, perciò l'ho sfruttata a fondo. Ho cercato in questo
modo di ottimizzare al massimo il programma, usando le stesse subroutine
per diverse parti del programma stesso.

Nell'ultima versione ho aggiunto la localizzazione, mediante la quale è
possibile cambiare le intestazioni degli ASL e dei gadget (la versione
originale è comunque italiana). Il file catalog può essere variato tramite
altri programmi PD.




Questo programma mi ha permesso di capire meglio la costruzione dei gadget
e delle finestre, ed inoltre dei metodi di sorting (tratti da un metodo di
sorting originale in basic, veramente efficace !!).

NB:    una volta iniziata l'elaborazione, non è più possibile fermarla,
perciò attenzione, perchè il multitasking viene molto limitato dall'uso
intensivo della funzione ParsePattern, che lo rallenta notevolmente.
Personalmente ho elaborato tutti i file autodoc nella pausa del pranzo